An openedx_catalog app with a representation for CourseRuns [FC-0117] by bradenmacdonald · Pull Request #479 · openedx/openedx-core

bradenmacdonald · 2026-02-10T03:11:23Z

An implementation of #469.

Related platform PR: openedx/openedx-platform#38023

Notes

This adds a new dependency on edx-organizations (which also requires Pillow for the logo field)
This uses opaque-keys, which was already an indirect dependency but not used directly
Before this PR, only course runs have a display_name, and catalog courses do not have names nor exist in the core platform at all. I'm proposing we add a display_name field to the new core CatalogCourse model to support various use cases, including the proposed new studio home page. See the code for how this can be backfilled and how runs can always override the name for each run.
This PR does not really include a CRUD API (neither python nor REST) for manipulating CatalogCourse/CourseRun objects; just a minimal API that platform code can use to keep them in sync with CourseOverview.
However, this PR does include complete Django admin views that admins and developers can use for provisioning course runs, deleting course runs, testing data migrations, etc.
This current does NOT allow course runs to have a different course code or org code from other runs of the same catalog course. (This restriction could be loosened in the future.) However, the org code capitalization may vary among runs.
Currently, it is the course_overviews app that syncs data from modulestore -> CourseOverview -> openedx_catalog. It would be more robust and future-friendly to instead sync data directly from SplitModulestoreCourseIndex -> openedx_catalog , but it's harder to get information like display_name and language in the latter case as that's not available in the SplitModulestoreCourseIndex table. It could be retrieved from Mongo though.
This PR bakes into the data model the assumption that all runs of the same catalog course are in the same language. Discussion on Slack
Because these models are updated by CourseOverview based on the course_published signal, any test cases in platform that want to use these models have to be sure to enable that signal, which is disabled for test by default.
⚠️ Because we rely on signals to update CourseRun when CourseOverview is updated, and CourseOverview itself is updated after courses are already created, it's possible that an error will occur and the CourseRun will never get created or updated. This will result in an error in the logs, but will not block course creation etc., so the error is likely to go unnoticed with the system as it exists today.

Architecture Diagram

See ARCHITECTURE.md.

Questions

Are org_code and course_code good terms to use? Should I call the latter number instead, like other parts of the code do? Should I call the org part org_short_name ?
Is the new url_code for each CatalogCourse useful? Do we want to make it editable now, or in the future?
Should we mark [parts of] this new catalog API as unstable?

Can be addressed later:

Should we make the new CourseRun a SoftDeletableModel to support course deletion without data loss? (Maybe we can't now, because soft-deleting it in that one table wouldn't affect the other tables that the system actually references. But in the future we could add this.)
Is "Course Schedule" a core concept that should live in this catalog app? I think yes, but it could also have a draft/publish workflow and ultimately live in openedx_content
Is "Course Visibility" a core concept that should be in this catalog app? (We actually have it defined as catalog_visibility, visible_to_staff_only, and course_visibility which all have different effects and different enum values, and also need to support "use system default")
Integrate authz ?
Check if we should deprecate edx-organization's OrganizationCourse
test what happens to enrollments if course is deleted then re-created with different capitalization (not even using this PR)

openedx-webhooks · 2026-02-10T03:11:28Z

Thanks for the pull request, @bradenmacdonald!

This repository is currently maintained by @axim-engineering.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

ormsbee · 2026-02-11T22:48:45Z

There is no stable/portable identifier for CatalogCourse objects, only their internal integer database ID. Do we need this? (An opaque key or something else?)

I don't know if we'll force it to be stable, but we'll probably want a SlugField(allow_unicode=True) so that we can address it in URLs in a descriptive looking way.

bradenmacdonald · 2026-02-24T18:00:28Z

There is no stable/portable identifier for CatalogCourse objects, only their internal integer database ID. Do we need this? (An opaque key or something else?)

I don't know if we'll force it to be stable, but we'll probably want a SlugField(allow_unicode=True) so that we can address it in URLs in a descriptive looking way.

Historical note: Apparently there was an old PR to add an opaque key for catalog courses, but it never merged: openedx/opaque-keys#87 Seems like they were called "aggregate courses" then.

…ng changed

…n that

kdmccormick

Partial review as I'm signing off for tonight, but overall really solid. I appreciate the comments and validation a lot. My only concerns so far are some superficial naming stuff.

src/openedx_catalog/models/course_run.py

src/openedx_catalog/models/catalog_course.py

src/openedx_catalog/models/course_run.py

kdmccormick · 2026-02-26T23:54:31Z

src/openedx_catalog/models/course_run.py

+            # Enforce that the course ID must end with "+run" where "run" is an exact match for the "run" field.
+            # This check may be removed or changed in the future if our course ID format ever changes
+            models.CheckConstraint(
+                # Note: EndsWith() on SQLite is always case-insensitive, so we code the constraint like this:
+                condition=Exact(Right("course_id", Length("run") + 1), Concat(models.Value("+"), "run")),
+                name="oex_catalog_courserun_courseid_run_match_exactly",
+                violation_error_message=_("The CourseRun 'run' field should match the run in the course_id key."),
+            ),


I have a sense that we'll eventually want to relax this in order to allow sites more flexibility on how they market their course runs, but I agree with adding the constraint for now and seeing how it plays out.

Turns out that I already had to relax it a bit, because it was breaking on CCX keys like ccx-v1:org+code+run+ccx@1 which don't end with +run. In fact, I realized CCX keys break a few different assumptions here - they also violate the constraint that (org, code, run) is unique per course run, because all CCX variants of a run have the same base course ID.

@bradenmacdonald I'm rusty on the CCX data model. Is every CCX considered a "course run" by the existing system? I know a CCX is a LearningContext, but does every CCX have a CourseOverview row?

Yes, every CCX instance is seen as a fully separate course run by most parts of the system (except Studio, which doesn't list them nor interact with them at all; CCX runs are created/edited/managed strictly through the LMS).

I just tested this now; here are the CourseOverviews of a CCX base course plus a CCX run created from it:

kdmccormick

(still reviewing)

src/openedx_catalog/signals.py

kdmccormick

Just a few requests for more words, looks great otherwise. I'll a look at the platform PR soon.

src/openedx_catalog/api_impl.py

src/openedx_catalog/README.rst

kdmccormick · 2026-03-02T16:32:15Z

src/openedx_catalog/models/course_run.py

+            # Enforce that the course ID must end with "+run" where "run" is an exact match for the "run" field.
+            # This check may be removed or changed in the future if our course ID format ever changes
+            models.CheckConstraint(
+                # Note: EndsWith() on SQLite is always case-insensitive, so we code the constraint like this:
+                condition=Exact(Right("course_id", Length("run") + 1), Concat(models.Value("+"), "run")),
+                name="oex_catalog_courserun_courseid_run_match_exactly",
+                violation_error_message=_("The CourseRun 'run' field should match the run in the course_id key."),
+            ),


@bradenmacdonald I'm rusty on the CCX data model. Is every CCX considered a "course run" by the existing system? I know a CCX is a LearningContext, but does every CCX have a CourseOverview row?

src/openedx_catalog/models/catalog_course.py

Co-authored-by: Kyle McCormick <kyle@axim.org>

kdmccormick

Just display_name -> title , otherwise LGTM.

I haven't manually tested this PR specifically, but I'll manually test the openedx-platform PR and call some of these API methods from the terminal, which should cover both PRs.

kdmccormick

Just tested again, looks great. Other than display_name->title, just one note.

src/openedx_catalog/api_impl.py

Co-authored-by: Kyle McCormick <kyle@axim.org>

openedx-webhooks added open-source-contribution PR author is not from Axim or 2U core contributor PR author is a Core Contributor (who may or may not have write access to this repo). labels Feb 10, 2026

openedx-webhooks added this to Contributions Feb 10, 2026

github-project-automation bot moved this to Needs Triage in Contributions Feb 10, 2026

mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Feb 10, 2026

bradenmacdonald added the FC Relates to an Axim Funded Contribution project label Feb 10, 2026

bradenmacdonald changed the title ~~An openedx_catalog app with a representation for CourseRuns~~ An openedx_catalog app with a representation for CourseRuns [FC-0117] Feb 10, 2026

bradenmacdonald force-pushed the braden/catalog branch from 17b313f to 8177a58 Compare February 13, 2026 19:51

bradenmacdonald changed the base branch from main to kdmccormick/root-packages February 13, 2026 19:51

Base automatically changed from kdmccormick/root-packages to main February 13, 2026 20:00

bradenmacdonald force-pushed the braden/catalog branch 5 times, most recently from 87f845c to ccebc9d Compare February 19, 2026 01:27

bradenmacdonald mentioned this pull request Feb 19, 2026

feat: Use openedx_catalog app, backfill its CourseRuns [FC-0117] openedx/openedx-platform#38023

Open

bradenmacdonald force-pushed the braden/catalog branch 3 times, most recently from 88e2f82 to bf0fbd6 Compare February 22, 2026 03:28

bradenmacdonald marked this pull request as ready for review February 24, 2026 07:26

kdmccormick self-requested a review February 24, 2026 16:23

bradenmacdonald force-pushed the braden/catalog branch from 8d56dc0 to d67189d Compare February 25, 2026 00:43

bradenmacdonald mentioned this pull request Feb 25, 2026

(WIP) feat: implement Pathways #482

Draft

bradenmacdonald added 4 commits February 26, 2026 14:31

feat: depend on edx-organizations

d8b8885

feat: new catalog app to model course runs and catalog courses

1c225aa

feat: add a pre_save hook to prevent Organization.short_name from bei…

da80093

…ng changed

feat: admin improvements - display CourseRun warnings

caf8a21

bradenmacdonald added 7 commits February 26, 2026 14:31

fix: bug found by the new tests

c5d43ae

refactor: update to use opaque-keys 3.1

162089b

test: expand tests, fix a bug with logging

3773103

docs: some parts of platform call the course_code "number", so mentio…

442eec1

…n that

chore: fix import order

edc943d

docs: clarify CatalogCourse.language is "primary language"

d804a4e

feat: API for deleting a course run and/or catalog course

b83e3f7

bradenmacdonald force-pushed the braden/catalog branch from ac60e0e to b83e3f7 Compare February 26, 2026 22:31

chore: fix lint issue

d8deaa2

kdmccormick requested changes Feb 26, 2026

View reviewed changes

kdmccormick self-requested a review February 26, 2026 23:57

fix: CourseRun database constraint wasn't working with CCX keys

43f7b7c

bradenmacdonald force-pushed the braden/catalog branch from 4dd8ad7 to 43f7b7c Compare February 27, 2026 00:50

refactor: course_id -> course_key, run -> run_code

88aef75

kdmccormick reviewed Feb 27, 2026

View reviewed changes

src/openedx_catalog/signals.py Show resolved Hide resolved

kdmccormick self-requested a review February 27, 2026 22:29

refactor: address review comments

1b6477c

bradenmacdonald mentioned this pull request Feb 27, 2026

Opaque Key Simplification? openedx/opaque-keys#411

Open

bradenmacdonald added 2 commits February 27, 2026 14:49

chore: fix quality

2c8385f

fix: missed update in Django admin

ccf075c

kdmccormick requested changes Mar 2, 2026

View reviewed changes

src/openedx_catalog/models/catalog_course.py Outdated Show resolved Hide resolved

bradenmacdonald and others added 2 commits March 2, 2026 14:18

docs: apply minor renames from code review

8f2a735

Co-authored-by: Kyle McCormick <kyle@axim.org>

docs: clarifications

a27856f

kdmccormick reviewed Mar 5, 2026

View reviewed changes

kdmccormick approved these changes Mar 5, 2026

View reviewed changes

src/openedx_catalog/api_impl.py Show resolved Hide resolved

bradenmacdonald and others added 4 commits March 5, 2026 09:40

feat: rename display_name -> title

a56a75b

feat: add assert to clarify misuse of get_catalog_course()

a045f92

Co-authored-by: Kyle McCormick <kyle@axim.org>

chore: update with latest main branch

2dee8e3

test: update tests for display_name -> title

995b9d4

Conversation

bradenmacdonald commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Architecture Diagram

Questions

Uh oh!

openedx-webhooks commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ormsbee commented Feb 11, 2026

Uh oh!

bradenmacdonald commented Feb 24, 2026

Uh oh!

kdmccormick left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kdmccormick Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

bradenmacdonald Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

kdmccormick Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

bradenmacdonald Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

kdmccormick left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kdmccormick left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kdmccormick Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kdmccormick left a comment

Choose a reason for hiding this comment

Uh oh!

kdmccormick left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bradenmacdonald commented Feb 10, 2026 •

edited

Loading

openedx-webhooks commented Feb 10, 2026 •

edited

Loading

kdmccormick left a comment •

edited

Loading